#Domino Designer
Posts tagged #Domino Designer · 29 posts
- @SetEnvironment and SetEnvironmentVar: Those "Environment Variables" Live in the notes.ini of Whatever Machine Runs the Code
To stash a setting from Formula or LotusScript, you've got a pile of look-alikes: @SetEnvironment, @Environment, session.SetEnvironmentVar, GetEnvironmentString. What they actually read and write is the notes.ini of the machine running the code — per-machine, not shared, not replicated. Plus a $-prefix rule that trips people up (Formula and LS prepend $ by default; reading a native notes.ini setting needs a flag). This piece pins down where they write, where the $ comes from, when to use them, and when to switch to a profile document instead.
2026.09.22 - The Unread-Marks Trap: They're Per-User, Not a Property of the Document
A document goes bold with a star beside it — the unread mark looks like a field on the document, but it isn't. It's one of the few things in Domino kept per user: your having read it doesn't mean anyone else has. Driving it from LotusScript with MarkRead/MarkUnread, it's easy to mark for the wrong user (an agent runs as one ID and only touches that ID's unread state); and unread marks don't replicate by default, so the server and your local replica routinely disagree on what's read. This piece explains the mechanism and three traps.
2026.09.21 - XPages Save Conflicts: Why You Get One Even When You're the Only User
"Document has been saved by another user" — except no one else is touching the document, yet a save conflict shows up now and then anyway. This is an old XPages trap: mixing the dominoDocument data source's save with a back-end Document save on the same document makes Domino's conflict detection misfire and spawn a conflict document. Starting from the official conflict mechanism ($Revisions), it breaks down assono's classic reproduction and re-tests this 2013-era gotcha on both Domino 12.0.2 and 14.5.1.
2026.09.16 - NotesView AutoUpdate=False: Why Modifying Documents in a View Loop Slows Down and Throws 'Entry not found in index'
An agent loops a view, tweaks each document, and gets slower and slower — sometimes even throwing 'Entry not found in index.' The culprit: NotesView refreshes itself by default, so when your loop modifies the very documents the view indexes, the view keeps re-sorting under your feet — killing performance and invalidating your navigation position. The fix is one line before the loop: view.AutoUpdate = False. This piece explains the mechanism, the correct 'grab the next handle before modifying' pattern, and three side effects to know (snapshot, current-code-only, must Refresh to see updates).
2026.09.15 - NoteID, UNID, @DocumentUniqueID: What Actually Separates Domino's Three Document IDs
To point at a Domino document you might grab its NoteID, its UniversalID (UNID), or use @DocumentUniqueID in Formula — three that look alike and behave nothing alike. A NoteID only means something inside one database file and changes across replicas; the UNID is a 32-character identity that's identical across every replica; @DocumentUniqueID returns that UNID (but without @Text it's a doclink, not text). This piece pins down each one's scope, stability, and when to use it — including the 'change the UNID and it becomes a new document' and 'save a duplicate UNID and get error 4000' traps, and where that /0/UNID in web URLs comes from.
2026.09.14 - Multi-Select Attachment Delete in XPages: Native Deletes One at a Time — Add 'Check Several, Delete on Save'
The XPages File Download control gives you one delete link per row — one attachment at a time — with no native 'check several, delete together.' Even a fully built production form lacks it. This piece first clears up something by testing: the native delete is actually 'commit on save' and well-behaved; then it adds multi-select batch delete with the same save-bounded official API (NotesXspDocument.removeAttachment), building a real check-mark, reversible, one-save implementation on a test server (Domino 12.0.2).
2026.09.13 - XPages File Upload Failing: The xspupload Temp Folder Wiped by Windows cleanmgr — Root Cause and Fixes (Including the 14.0 Fix)
The XPages file upload control does nothing — no client-side error, the page is fine, the file just doesn't upload — while the server console throws IOFileUploadException 'The system cannot find the path specified'. The root cause: Domino's upload temp folder xspupload is gone, often because Windows Disk Cleanup (cleanmgr) wiped the temp files while Domino was running. This piece ties the official KBs to real practice: the symptom and root cause, why the folder disappears, and the fixes — from the 'cycle HTTP every night' band-aid to notes_tempdir, a programmatic check-and-recreate, and upgrading to 14.0 where the defect is fixed.
2026.09.12 - Classic Domino Web Attachment UI Tricks: Hide the Crude Default with $V2AttachmentOptions, Then Draw Your Own List and Delete
Drop a File Upload Control on a Domino web form, add a save button, and it works — but it looks crude: Domino dumps the attachments at the bottom of the page, and in edit mode adds a row of un-styleable 'mark for deletion' checkboxes. This piece covers the classic Domino web developer's toolkit: hide the default attachment area with $V2AttachmentOptions="0", draw your own download list with pass-through HTML and @AttachmentNames, and the rarely-explained delete mechanism %%Detach (roll your own checkboxes, or use WebQuerySave). Includes the gotchas: $V2AttachmentOptions is 0/1 only, and it's text not a number.
2026.09.11 - Multi-File Upload and Selective Attachment Delete in Domino: Classic Web and XPages 14.5.1
The last piece covered attaching one file three ways; this one goes to 'many at once': a classic web form uses the HTML5 multiple attribute to select several files, XPages only got native multi-select by default in 14.5.1 (before that it was OpenNTF community controls), and the case you actually hit most but is thinly documented — deleting attachments by criteria: iterate EmbeddedObjects and Remove by a condition on .Source (with a runnable example). With a figure showing how the selected files land in one rich text field.
2026.09.09 - File Attachments in Domino Three Ways: Notes Client, Classic Web Form, and XPages
Attaching a file in the Notes client is so easy it barely feels like a feature — drag it into a rich text field, done. But move that same need to the web, or into XPages, and 'how do users upload a file' becomes three different answers: the client uses a rich text field, a classic web form uses the File Upload Control embedded element, and XPages uses xp:fileUpload paired with xp:fileDownload. This piece lines up the three front-end upload mechanisms and points out the reassuring part — all three land as an attachment on the same rich text field of the document, so the backend code to list, extract, and delete them is shared.
2026.09.08 - A Cross-DB Embedded View Won't Start in the Test Region? It's the Replica ID Baked into the DXL
A cross-database embedded view on a form worked fine in dev, then showed 'cannot start' the moment it reached the customer's test region. Nowhere in Designer's embedded-view UI is there a field to change the source database. Export the form to DXL and the reason shows up: the embeddedview element pins its source by the source database's replica ID — change environments and that ID no longer resolves. This is a field report: how to diagnose it, how to swap it in bulk with a NotesDXLExporter/Importer agent, and the faster way I found afterward — editing the DXL directly in Designer.
2026.08.18 - Why Your Domino View Header Is Forever Off by One Column: Passthrough-HTML Black Magic
Inherit an old classic-web Domino view and you'll often find the column headers sitting one cell to the right of the data — and nobody knows why. A field report on the passthrough-HTML tricks hiding in twenty-year-old view designs: square-bracket HTML in column values and titles, spacer columns, per-row checkboxes, and the real culprit — an intentionally unclosed <input tag that swallows the </td><td> boundary and merges two columns into one cell, shifting every header after it.
2026.07.22 - GetAllDocumentsByKey in Multi-Level Categorized Views: Why Your Count Is Silently Wrong
In a single-level categorized view, GetAllDocumentsByKey('Belgien', True) correctly returns the 2 documents under that category. But add a second level of categorization — Form then Country — and GetAllDocumentsByKey('Customer', True) returns 3, not all the documents. It stops at the first sub-category. This article documents the empirically verified trap and the workarounds.
2026.07.09 - NSF ODP Tooling: Build Domino NSFs from Source, No Designer Required
NSF ODP Tooling is an OpenNTF project that turns a binary NSF into a file-system On-Disk Project you can keep in Git, then compiles it back into a full NSF without Domino Designer — bringing real version control and CI/CD to Domino. Here's what it is, how the Maven plugin and container-based compilation work, and what the 4.1.0 release actually changed.
2026.06.27 - NotesOutline + NotesOutlineEntry Deep Dive — Programmatic UI Navigation in Domino, 4 Entry Types, 24 Properties
NotesOutline is the Domino design element behind the navigation menu in a Notes application, made up of NotesOutlineEntry items in a tree. From LotusScript you can dynamically build, modify, and walk an outline — typical use cases are multilingual menus (updating Label per user locale), role-conditional menus (hiding entries by ACL role), and personalized navigation. This guide covers the NotesOutline ↔ NotesOutlineEntry relationship, 8 tree-walking methods, 6 manipulation methods, all 24 entry properties, the 4 Set* methods, the 4 entry type constants and 9 EntryClass constants, a complete CRUD example, five pitfalls, and Java/SSJS counterparts.
2026.05.20 - Parsing XML in LotusScript — DOM or SAX? Five Questions That Pick the Right Tool
LotusScript offers three routes for XML processing: NotesDOMParser (whole-tree load), NotesSAXParser (event-driven streaming), and NotesXMLProcessor + NotesXSLTransformer (rule-based XSLT transformation). This guide compares the three at a fundamental level, walks five decision questions (file size / modification needs / traversal direction / memory budget / transformation scenario), gives practical scenario picks, code-style side-by-side, performance numbers, and a consolidated pitfalls table. After reading you'll know exactly which tool to reach for when an XML file lands.
2026.05.18 - NotesDOMParser Deep Dive — Loading XML into a DOM Tree, 14 Node Classes, Walking / Modifying / Serializing
NotesDOMParser loads the entire XML into memory as a DOM tree — with NotesDOMDocumentNode as the root and 14 Node subclasses (Element / Text / Attribute / Comment / CDATA / ...) representing XML constructs. You can walk anywhere, modify anything, and Serialize back to XML output. This guide covers the DOM tree model, CreateDOMParser, the 14 Node class relationships, NotesDOMNode's tree-walking API (FirstChild / NextSibling / NodeType), a complete parse → walk → modify → serialize example, five pitfalls, and Java/SSJS counterparts.
2026.05.17 - NotesSAXParser Deep Dive — LotusScript Streaming XML Parsing, 12 SAX Events, On Event Binding
NotesSAXParser processes XML in SAX (Simple API for XML) event-driven mode — instead of loading the file into memory, it fires SAX_StartElement / SAX_Characters / SAX_EndElement and other events as it reads through. The right choice for large files, read-only access, or memory-constrained scenarios. This guide covers the SAX-vs-DOM distinction, CreateSAXParser initialization, On Event binding, when each of the 12 events fires, how NotesSAXAttributeList exposes attributes, a complete LotusScript example, five common pitfalls, and the Java/SSJS counterparts.
2026.05.16 - NotesSession Deep Dive — LotusScript's Entry Point, the Single-Instance Rule, Three UserName Variants, and Evaluate
NotesSession is the class every LotusScript script reaches for first — it represents the current script's runtime environment and gives you CurrentDatabase, three user-name properties (UserName, EffectiveUserName, CommonUserName), Evaluate for running @Formula from LS, CreateLog for NotesLog, GetEnvironmentString for notes.ini reads. This guide covers the class's role, the one-session-per-script rule, key properties and methods, the three UserName variants and how they diverge under On Behalf Of agents, server-side vs workstation access-level differences, five common pitfalls, and a complete example.
2026.05.14 - NotesDocument Deep Dive — The Core LotusScript Class, Its CRUD Surface, and Five Pitfalls
NotesDocument is the core class LotusScript uses for any Domino document operation — but the details trip people up: GetItemValue always returns an array (even single values), Save's createResponse parameter is widely misread (it's not how you create response documents), Remove's force flag isn't a soft-delete switch (that's a database-level setting; use RemovePermanently to bypass it), the subtle difference between direct property syntax and ReplaceItemValue, and forgetting .Save is the most common silent bug. This guide covers every way to obtain a NotesDocument, the Item vs Field distinction, CRUD examples, the five must-know pitfalls, sibling methods, and the Java/SSJS counterparts.
2026.05.13 - NotesView.GetAllDocumentsByKey: The Lookup Workhorse, and Five Things That Trip People Up
GetAllDocumentsByKey is the LotusScript lookup method everyone uses — pass a key, get back the matching documents. But the small print — keys match the view's sorted column (not document fields), exactMatch defaults to False (so it's prefix-match unless you opt in), backslash-categorised columns silently break it, and the returned collection has no defined order — gets missed even by experienced devs. This piece walks the signature, the by-key family, five real pitfalls, and complete examples.
2026.05.09 - LotusScript's Outbound HTTP / JSON Toolchain: NotesHTTPRequest + NotesJSONNavigator
Domino V12 added NotesHTTPRequest and NotesJSONNavigator to LotusScript, so calling an external REST API and parsing the JSON response is finally a self-contained LS workflow — no more ActiveX shims or shelling out to curl. This guide covers both classes' methods and properties, the PreferJSONNavigator property that wires them together as an official path, a complete example, and where Java / SSJS land in comparison.
2026.05.07 - NotesXMLProcessor: The Common Base for LotusScript XML Handling
NotesXMLProcessor is the abstract base class behind every LotusScript XML handler — DOMParser, SAXParser, DXLExporter, DXLImporter, and XSLTransformer all inherit from it. This guide covers the role it plays, the five derived classes and when to pick which, the inherited properties, the SetInput / SetOutput / Process trio, and the Release 6 / no-COM caveats that don't make it into most quick refs.
2026.05.06 - DQL Production-Ready: Catalog Maintenance, Permissions, and sessionAsSigner
The two real walls when shipping DQL to production: how the Design Catalog gets maintained automatically (bootstrapping brand-new NSFs, incremental refresh after design changes), and why regular users hit the 'You don't have permission' error — plus the sessionAsSigner / scheduled-agent solutions. The final pattern is verified against Domino 12 production logs, with a production-ready Java helper class to drop in.
2026.05.03 - A Practical Guide to LotusScript NotesStream: Files Done Right
NotesStream is the LotusScript abstraction for reading and writing files from a Notes/Domino agent. This guide walks through the real Open signature, the Truncate-before-write pattern, text vs binary I/O, and the gotchas the official documentation actually warns about.
2026.05.02 - DQL Pitfalls: 6 Query-Writing Details the Official Docs Don't Spell Out
Domino Query Language (DQL)'s syntax looks SQL-like, but writing real queries surfaces a whole set of Notes-specific traps — view selection silently scopes results, the `'view'.column` references the view column's programmatic name (not a doc field), comparison operators need whitespace on both sides, backslashes in view names need escaping, `@formula` is a separate Formula Language parser, and string-stored date fields need `@TextToTime`. Each trap below comes with the verbatim error message and a working fix.
2026.05.01 - NotesRichTextItem: writing rich text fields from LotusScript
NotesRichTextItem inherits from NotesItem, so every NotesItem property and method is already available — but it adds 22 methods of its own for paragraph styles, tables, embedded objects, and Navigator/Range traversal of existing rich-text content. This post catalogues construction, the 22 methods grouped by purpose, the inheritance contract, and the gotchas you hit in real code.
2026.04.30 - NotesNoteCollection: the Swiss-army tool for NSF design elements
NotesNoteCollection is not a NotesDocumentCollection variant — it represents every kind of 'note' in an NSF, including data documents AND design elements (forms, views, agents, ACL, code libraries). This post catalogues the 32 properties, 14 methods, the True/False initialisation parameter on CreateNoteCollection, and its most common real-world use: feeding NotesDXLExporter.
2026.04.29 - NotesViewNavigator: navigate views the proper way, not GetFirstDocument loops
NotesViewNavigator is the LotusScript tool for non-trivial view traversal: it returns ViewEntry objects (which carry view metadata GetFirstDocument doesn't), it can be built over a subset of the view (a single category, all unread, descendants of an entry, a max level), and it's faster than the naive document loop — provided you remember to switch AutoUpdate off first. This post catalogues the 4 properties, ~36 methods, 7 CreateViewNav* variants, and the caveats worth knowing.
2026.04.29